home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_perl.idb / usr / freeware / catman / u_man / cat1 / c2ph.Z / c2ph
Encoding:
Text File  |  1998-10-28  |  10.3 KB  |  331 lines
  1.  
  2.  
  3.  
  4.      CCCC2222PPPPHHHH((((1111))))         22223333////OOOOcccctttt////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))           CCCC2222PPPPHHHH((((1111))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.       c2ph,    pstruct    - Dump C structures as generated from cc -g -S
  10.       stabs
  11.  
  12.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.           c2ph [-dpnP] [var=val] [files ...]
  14.  
  15.  
  16.       OOOOPPPPTTTTIIIIOOOONNNNSSSS
  17.  
  18.           Options:
  19.  
  20.           -w  wide;    short for: type_width=45 member_width=35 offset_width=8
  21.           -x  hex; short for:  offset_fmt=x    offset_width=08    size_fmt=x size_width=04
  22.  
  23.           -n  do not generate perl code  (default when invoked as pstruct)
  24.           -p  generate perl    code         (default when invoked as c2ph)
  25.           -v  generate perl    code, with C decls as comments
  26.  
  27.           -i  do NOT recompute sizes for intrinsic datatypes
  28.           -a  dump information on intrinsics also
  29.  
  30.           -t  trace    execution
  31.           -d  spew reams of    debugging output
  32.  
  33.           -slist  give comma-separated list    a structures to    dump
  34.  
  35.  
  36.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  37.       The following    is the old c2ph.doc documentation by Tom
  38.       Christiansen <tchrist@perl.com> Date:    25 Jul 91 08:10:21 GMT
  39.  
  40.       Once upon a time, I wrote a program called pstruct.  It was
  41.       a perl program that tried to parse out C structures and
  42.       display their    member offsets for you.     This was especially
  43.       useful for people looking at binary dumps or poking around
  44.       the kernel.
  45.  
  46.       Pstruct was not a pretty program.  Neither was it
  47.       particularly robust.    The problem, you see, was that the C
  48.       compiler was much better at parsing C    than I could ever hope
  49.       to be.
  50.  
  51.       So I got smart:  I decided to    be lazy    and let    the C compiler
  52.       parse    the C, which would spit    out debugger stabs for me to
  53.       read.     These were much easier    to parse.  It's    still not a
  54.       pretty program, but at least it's more robust.
  55.  
  56.       Pstruct takes    any .c or .h files, or preferably .s ones,
  57.       since    that's the format it is    going to massage them into
  58.       anyway, and spits out    listings like this:
  59.  
  60.  
  61.  
  62.  
  63.      Page 1                        (printed 10/23/98)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      CCCC2222PPPPHHHH((((1111))))         22223333////OOOOcccctttt////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))           CCCC2222PPPPHHHH((((1111))))
  71.  
  72.  
  73.  
  74.        struct tty {
  75.          int              tty.t_locker                   000    4
  76.          int              tty.t_mutex_index               004    4
  77.          struct tty    *          tty.t_tp_virt                   008    4
  78.          struct clist          tty.t_rawq                   00c     20
  79.            int              tty.t_rawq.c_cc               00c    4
  80.            int              tty.t_rawq.c_cmax               010    4
  81.            int              tty.t_rawq.c_cfx               014    4
  82.            int              tty.t_rawq.c_clx               018    4
  83.            struct tty *          tty.t_rawq.c_tp_cpu               01c    4
  84.            struct tty *          tty.t_rawq.c_tp_iop               020    4
  85.            unsigned    char *          tty.t_rawq.c_buf_cpu               024    4
  86.            unsigned    char *          tty.t_rawq.c_buf_iop               028    4
  87.          struct clist          tty.t_canq                   02c     20
  88.            int              tty.t_canq.c_cc               02c    4
  89.            int              tty.t_canq.c_cmax               030    4
  90.            int              tty.t_canq.c_cfx               034    4
  91.            int              tty.t_canq.c_clx               038    4
  92.            struct tty *          tty.t_canq.c_tp_cpu               03c    4
  93.            struct tty *          tty.t_canq.c_tp_iop               040    4
  94.            unsigned    char *          tty.t_canq.c_buf_cpu               044    4
  95.            unsigned    char *          tty.t_canq.c_buf_iop               048    4
  96.          struct clist          tty.t_outq                   04c     20
  97.            int              tty.t_outq.c_cc               04c    4
  98.            int              tty.t_outq.c_cmax               050    4
  99.            int              tty.t_outq.c_cfx               054    4
  100.            int              tty.t_outq.c_clx               058    4
  101.            struct tty *          tty.t_outq.c_tp_cpu               05c    4
  102.            struct tty *          tty.t_outq.c_tp_iop               060    4
  103.            unsigned    char *          tty.t_outq.c_buf_cpu               064    4
  104.            unsigned    char *          tty.t_outq.c_buf_iop               068    4
  105.          (*int)()              tty.t_oproc_cpu               06c    4
  106.          (*int)()              tty.t_oproc_iop               070    4
  107.          (*int)()              tty.t_stopproc_cpu               074    4
  108.          (*int)()              tty.t_stopproc_iop               078    4
  109.          struct thread *          tty.t_rsel                   07c    4
  110.  
  111.       etc.
  112.  
  113.       Actually, this was generated by a particular set of options.
  114.       You can control the formatting of each column, whether you
  115.       prefer wide or fat, hex or decimal, leading zeroes or
  116.       whatever.
  117.  
  118.       All you need to be able to use this is a C compiler than
  119.       generates BSD/GCC-style stabs.  The ----gggg option    on native BSD
  120.       compilers and    GCC should get this for    you.
  121.  
  122.       To learn more, just type a bogus option, like    ----\\\\????, and a
  123.       long usage message will be provided.    There are a fair
  124.       number of possibilities.
  125.  
  126.  
  127.  
  128.  
  129.      Page 2                        (printed 10/23/98)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      CCCC2222PPPPHHHH((((1111))))         22223333////OOOOcccctttt////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))           CCCC2222PPPPHHHH((((1111))))
  137.  
  138.  
  139.  
  140.       If you're only a C programmer, than this is the end of the
  141.       message for you.  You    can quit right now, and    if you care
  142.       to, save off the source and run it when you feel like    it.
  143.       Or not.
  144.  
  145.       But if you're    a perl programmer, then    for you    I have
  146.       something much more wondrous than just a structure offset
  147.       printer.
  148.  
  149.       You see, if you call pstruct by its other incybernation,
  150.       c2ph,    you have a code    generator that translates C code into
  151.       perl code!  Well, structure and union    declarations at    least,
  152.       but that's quite a bit.
  153.  
  154.       Prior    to this    point, anyone programming in perl who wanted
  155.       to interact with C programs, like the    kernel,    was forced to
  156.       guess    the layouts of the C strutures,    and then hardwire
  157.       these    into his program.  Of course, when you took your
  158.       wonderfully crafted program to a system where    the sgtty
  159.       structure was    laid out differently, you program broke.
  160.       Which    is a shame.
  161.  
  162.       We've    had Larry's h2ph translator, which helped, but that
  163.       only works on    cpp symbols, not real C, which was also    very
  164.       much needed.    What I offer you is a symbolic way of getting
  165.       at all the C structures.  I've couched them in terms of
  166.       packages and functions.  Consider the    following program:
  167.  
  168.           #!/usr/local/bin/perl
  169.  
  170.           require 'syscall.ph';
  171.           require 'sys/time.ph';
  172.           require 'sys/resource.ph';
  173.  
  174.           $ru = "\0" x &rusage'sizeof();
  175.  
  176.           syscall(&SYS_getrusage, &RUSAGE_SELF, $ru)      && die "getrusage: $!";
  177.  
  178.           @ru = unpack($t =    &rusage'typedef(), $ru);
  179.  
  180.           $utime =    $ru[ &rusage'ru_utime +    &timeval'tv_sec     ]
  181.              + ($ru[ &rusage'ru_utime +    &timeval'tv_usec ]) / 1e6;
  182.  
  183.           $stime =    $ru[ &rusage'ru_stime +    &timeval'tv_sec     ]
  184.              + ($ru[ &rusage'ru_stime +    &timeval'tv_usec ]) / 1e6;
  185.  
  186.           printf "you have used %8.3fs+%8.3fu seconds.\n", $utime, $stime;
  187.  
  188.       As you see, the name of the package is the name of the
  189.       structure.  Regular fields are just their own    names.    Plus
  190.       the following    accessor functions are provided    for your
  191.       convenience:
  192.  
  193.  
  194.  
  195.      Page 3                        (printed 10/23/98)
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.      CCCC2222PPPPHHHH((((1111))))         22223333////OOOOcccctttt////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))           CCCC2222PPPPHHHH((((1111))))
  203.  
  204.  
  205.  
  206.           struct      This takes no    arguments, and is merely the number of first-level
  207.               elements in the structure.  You would    use this for indexing
  208.               into arrays of structures, perhaps like this
  209.  
  210.                   $usec = $u[ &user'u_utimer
  211.                       + (&ITIMER_VIRTUAL * &itimerval'struct)
  212.                       + &itimerval'it_value
  213.                       + &timeval'tv_usec
  214.                     ];
  215.  
  216.           sizeof      Returns the bytes in the structure, or the member if
  217.               you pass it an argument, such    as
  218.  
  219.                   &rusage'sizeof(&rusage'ru_utime)
  220.  
  221.           typedef      This is the perl format definition for passing to pack and
  222.               unpack.  If you ask for the typedef of a nothing, you    get
  223.               the whole structure, otherwise you get that of the member
  224.               you ask for.    Padding    is taken care of, as is    the magic to
  225.               guarantee that a union is unpacked into all its aliases.
  226.               Bitfields are    not quite yet supported    however.
  227.  
  228.           offsetof      This function    is the byte offset into    the array of that
  229.               member.  You may wish    to use this for    indexing directly
  230.               into the packed structure with vec() if you're too lazy
  231.               to unpack it.
  232.  
  233.           typeof      Not to be confused with the typedef accessor function, this
  234.               one returns the C type of that field.     This would allow
  235.               you to print out a nice structured pretty print of some
  236.               structure without knoning anything about it beforehand.
  237.               No args to this one is a noop.  Someday I'll post such
  238.               a thing to dump out your u structure for you.
  239.  
  240.       The way I see    this being used    is like    basically this:
  241.  
  242.           % h2ph <some_include_file.h  >  /usr/lib/perl/tmp.ph
  243.           % c2ph  some_include_file.h  >> /usr/lib/perl/tmp.ph
  244.           % install
  245.  
  246.       It's a little    tricker    with c2ph because you have to get the
  247.       includes right.  I can't know    this for your system, but it's
  248.       not usually too terribly difficult.
  249.  
  250.       The code isn't pretty    as I mentioned    -- I never thought it
  251.       would    be a 1000- line    program    when I started,    or I might not
  252.       have begun. :-)  But I would have been less cavalier in how
  253.       the parts of the program communicated    with each other, etc.
  254.       It might also    have helped if I didn't    have to    divine the
  255.       makeup of the    stabs on the fly, and then account for micro
  256.       differences between my compiler and gcc.
  257.  
  258.  
  259.  
  260.  
  261.      Page 4                        (printed 10/23/98)
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.      CCCC2222PPPPHHHH((((1111))))         22223333////OOOOcccctttt////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))           CCCC2222PPPPHHHH((((1111))))
  269.  
  270.  
  271.  
  272.       Anyway, here it is.  Should run on perl v4 or    greater.
  273.       Maybe    less.
  274.  
  275.        --tom
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.      Page 5                        (printed 10/23/98)
  328.  
  329.  
  330.  
  331.